Program  :  DosShell 83z v 0.93
Author   :  Ahmed El-Helw
Date     :  August 8, 1997


Table of Contents
-----------------
1.  Introduction
2.  How the program works
3.  Editing Program names 
4.  Editing Program descriptions
5.  Adding your own programs
6.  Backgrounds
7.  Known Bugs
8.  Future Releases
9.  Version Updates
10. Contribute/Help!
11. Special Thanks
12. Contacting the author


NOTE - ALL SUBMITTED BACKGROUNDS WILL BE INCLUDED IN THIS ZIP!

1.  Introduction 

	This is the smallest ever ASM Shell - only about 500 bytes at start.  Of course small 
means bad right ?  Well, sometimes - not always.  This is a both ASM/Basic Shell - but don't get
discouraged - over 95 % of this program is in ASM.  To learn what is in ASM/Basic, read the next
section, How the Program Works.  Now - the name "DosShell" may bring the vivid good old days of 
DOS - but not on the TI - nope - this is not the c:\ prompt.  if anyone (like me =) still has 
Windows 3.11/Dos, goto the command prompt and type "dosshell", and although my program and 
DOSSHELL have nothing in common, the reason I called it DosShell is because it is not that
advanced of a shell.  For Win95/Linux/Mac users, it is basically a File Manager clone - except
slower, and looks worse - therefore, this is what I named mine - DosShell.  This program was made
for 1 reason - not competition - because Bill's Aurora is the best OS out there for 83 ASM, and 
I don't disagree.  The reason i made this is because Bill didn't release his source, so I am 
releasing this source to help people learn ASM, and, because it should be the center of attention
for my ASM Journal V.

2.  How the program works

	Ok - as I said - this is ASM and basic - so, to start off, I will tell you how this works,
so that you can understand that the part in basic is really not much.  Here is how it works - a
basic program called "DOSSHELL" launches the ASM File - the ASM File offers almost everything the 
program has - but - this program does not have autodetect - since I am not that ASM adept.  Also,
I was trying to find out HOW to run programs from ASM , Bill told me it was complex =), and I bet
it was - therefore, I took an easy, yet effective way out.  What the program does is stores a 
number to X, and then, the basic program runs the program corresponding to the number.  Also -
you should know that there are only 3 default programs - you can easily add and subtract more, but
this is what this document will talk to you about.

Controls :

Clear - Quits
Plus - Increase Contrast
Minus - Decrease Contrast
Number - Run Program

3.  Changing a Program Name

	This is meant for those non ASM adept, those of you who don't care - then this is for you.
If you want to use the default names, but change the programs ran, that is easy.  Simply edit
the basic program, and change the prgmXXXXXXXX to whatever you want it to run.  That's it - to 
edit names, add more programs, etc, read on!  Note - If x=0 is a required part of the basic prog -
else - you cannot exit!

4.  Editing Program Descriptions

	If you run DosShell, you will notice that there are a default screen of the title, the
author's name, and 3 programs.  Now suppose you want to change the program names - for example,
instead of doing TurboBreakout II, you want it to say "Tetris" - that is very simple.  Simply open
the enclosed *.z80 that is enclosed.   Go down to the near end of the document, where you will
see commands that are like this :

.db 	"TurboBreakout II",0

To change a program name, simply edit this string and exchange the TurboBreakout II to Tetris. 
The end product will look like this :

.db	"Tetris",0

Now - then to get this to go on your calc, you must compile it - now I suggest you go to my 
homepage or the TI-Files, and read my ASM Journal I, but besides reading it, it is very important
that you download all the needed programs.  The URL's are at the bottom of this document.  Now,
take the files you downloaded, unzip them all to 1 directory.  Copy the *.z80 to that directory as
7well.  Then, at the dos prompt, goto that directory, and type :

zasm ZDOSHELL

Keeping the caps as they should be  -  make sure it says no errors - if it gave you an error, 
check to make sure that you did the string as above.  If it does correctly, send it to your calc.
Before you run the Basic Program, though, you need to go to The TI-Files or my page and download
Squish, a program that makes program half size,  then you must squish it - how you do that is 
easy.  Send the *.83p to your calc, and then, type :

"ZDOSHELL"
Press Enter

Send(9prgmSQUISH
Press Enter

Then - you can delete program Squish, and run the basic program.  Make any necessary editions to 
the basic program to run the correct programs.  If you need more help in compiling, then
read my ASM Journals, especially ASM Journal I.



5.  Adding Your own programs

	Firstly - as a precaution - back up your calc - you can't afford to make mistakes =).  
I recommend this section only to people who know SOME ASM, so they don't mess up big time.  
So - three programs not enough ?  There are a few places in the source you need to edit, though.
Luckily, all these places are marked by ;-------Start Editing Here ------ and ;End Editing here.
These are the places to edit.  I recommend you keep my ASM Journal with instructions on Getky near
by, you will need the Getky key commands.


First and easiest part - ok - you see the first ;Start Editing Here - that is where you will start.
this is the part that calls the strings for display on to the screen.  So, we look at this :


;------------Edit Here ----------------------------
	ld	hl,20*256+15
	ld	(pencol),hl
	ld	hl,option1
	call	_vputs
	ld	hl,27*256+15
	ld	(pencol),hl
	ld	hl,option2
	call	_vputs
	ld	hl,34*256+15
	ld	(pencol),hl
	ld	hl,option3
	call	_vputs

;------------End Edit Here ----------------------------


Now then, this should be simple enough.  We can see a pattern forming.  Here, ld hl,20*256+15 
does the following - it loads 20 into the penrow, and 15 into the column.  The 256 is required,
and I dunno why =).  Now then - ld (pencol),hl  - another required command - without it, it 
dosen't work =(.  Then , you actually load the string, so we do ld hl,option1.  This will display
the string under label "option 1" at that current cursor position.  Now - also notice that all 
pencol's are the same (15), and that the rows are 7 apart.  To add your own, here is what to do :

ld hl,41*256+15
ld (pencol),hl
ld hl,option4
call _vputs

All of that is tabbed, by the way.  And VPUTS IS VERY IMPORTANT!  Don't forget it.  After you did 
that - the hard part comes - but it isn't that hard =).  

The Getkey Loop :

Using Direct Input, this loop tells the calc where to go for each key pressed.  Again, keep my ASM
Journal on Direct Input out - by the way - there should be (by the time you are reading this) an
ASM Journal V for more help on this.


;------------Edit Here ----------------------------		
	
mainloop:					;Main program loop, with direct input       
	ld 	a,0ffh				;Reset port
	out 	(1),a				
	ld 	a,0fdh				;Loads in the new key port to search for key in
	out 	(1),a
	in 	a,(1)
	cp 	191				;If key is clear
	jp 	z,quit				;Exit label (quit)
	cp 	253				;If key is plus
	jp 	z,more				;Increase contrast label (more)
	cp 	251				;If key is minus
	jp 	z,less				;decrease contrast label  (less)
	ld 	a,0ffh
	out 	(1),a
	ld 	a,0efh
	out 	(1),a
	in 	a,(1)
	cp 	253
	jp	z,one
	ld 	a,0ffh
	out 	(1),a
	ld 	a,0f7h
	out 	(1),a
	in 	a,(1)
	cp 	253
	jp 	z,two
	ld 	a,0ffh
	out 	(1),a
	ld 	a,0fbh
	out 	(1),a
	in 	a,(1)
	cp 	253
	jp 	z,three
	jp	nz,mainloop

;-----------End Editions-----------------


Whoa - that's alot =).  Not really.  All I recommend you do before doing this is reading the part
of my ASM Journal on Direct Input - it is well explained, but this is a bit different - so I'll 
show you a little bit.


	ld 	a,0ffh				
	out 	(1),a				
	ld 	a,0fdh				
	out 	(1),a
	in 	a,(1)
	cp 	191				
	jp 	z,quit				
	

Now then - all of you reading my ASM Journal will tell me about #defines, those will work too.
The only difference is here, instead of referring to The key clear as kClear, we refer to it
as 191, because if you look at the defines in my Journal, it will say "equ. 191".  Therefore,
this is key 191 on this port - therefore, no need to do #Define - but - the keyport (0fdh) remains
the same.  Basically, ld a,0ffh tells the calc to clear the keyport, the out and in are required,
then all that happens is that you load the row of the key into a (0fdh) and then you say if key
is clear, goto quit - but in your new program, you will need to make a key for it - so again - 
read the ASM Journal on Direct Input - I will explain it though, in the ASM Journal V, once again.
So, if you don't understand now - read the ASM Journal V.  After you did find the port and key, 
give the program a label to goto, lets say z,four.  By the way, keep the "jp nz,mainloop" at the
very bottom of the loop.  


Now another easy part :

;-------------------Edit Here-------------------------------
one:
	call	_clrLCDFull		;Clear Screen
	ld	a,1			;Load 1->a
	call	_setxxop1		;Store a to OP1
	call	_stox			;Store op 1 to "X", the calculator basic x
	jp	exit			;Goto exit

two:
	call	_clrLCDFull
	ld	a,2
	call	_setxxop1
	call	_stox
	jp	exit

three:
	call	_clrLCDFull
	ld	a,3
	call	_setxxop1
	call	_stox
	jp	exit

;--------------------End Editions Here ----------------------------------

What does this do ?  Firstly - the labels are accordingly to the getkey loop.  So, if the loop 
says " if key is 1, goto label One", then label one is here.  Here is all this does - clears the
screen, stores a number into x, then goes to exit.  For our purposes, here is what we should do:

four:
	call	_clrLCDFull
	ld	a,4		;We need a different number here - so the calc can 
				;know program 3 from 4 when we are about to run it
	call	_setxxop1
	call	_stox
	jp	exit


The final and easiest change is the program name - so you need a new .db to display the program
name.  So we recall above, at our very first addition, we told it to call the string option4 to
the screen.  So, we'll goto the bottom of the doc where all the .db statements are, here :

;----------------Edit Here ---------------

option1:
	.db	"  1.  Spaze Invaders  ",0
option2:
	.db	"  2.  Insane Game  ",0
option3:
	.db	"  3.  Turbo Breakout II  ",0

;--------------End Edit Here -------------

Now - let's add our option.  So, that again is simple.  We do this :

option4:
	.db	"  4.  MineSweeper  ",0


That's it!  Now - all you gotta do is save and compile, then send to your calc, Squish it, then 
edit the basic program, and say that if x = 4, run program and the program name, then goto 0. 
That's all =).


6. Backgrounds

	Simply do a "RecallPic PicX" or put something on the grph screen, then it will 
	automatically put it as a background - else - clear screen and axes - it is
	also possible that the program doesn't automatically recognize a change, so
	try it once or twice.

7. Known Bugs 

	Not many known bugs, but among them are :

- Penguins doesn't run properly with DosShell - if you run Penguins with it - 
it will cause DosShell not to display program names - until you reset your calc. 

- Contrast may be a bit jumpy in an instant - the calc stores a number for halfway contrast
to a variable, therefore, if you edit the contrast, it will edit it from that halfway.  So
if your batteries are low - keep pressing plus till the contrast is good.

-Shut down must be done by pressing (*) then (/), and not by one key


8.  Future Releases 

	Hopefully, I want to add the following :

		- Fix Penguins Problem
		- Fix contrast problem
		- Add a background (see section 9)
		- Autodetect  ... 
		- Run via ASM, no basic program ...
		- Password ...
		- Auto Power Down ...

9. Version Updates
	DosShell
		v 0.93
			-Added the latest source (thanks Tony)
			-Added a shutdown feature
			-Added background support

		v 0.92
			-Second Release
			-Added the cool directory function!

		v. 0.9
			-Initial Release


10. Contributions / Help 

	Things to contribute/help with for DosShell :

			- A background!  Please =)
			- Someone tell me how to autodetect
			- Someone tell me how to run in ASM!
			- Comments - Please!

11. Special Thanks

My thanks for this program goes to David Erikson for his PROGPTR, Jonathon Bates for
bringing PROGPTR to my attention, Movax and Bill Nagel for answering my many ASM questions,
Andrew Ungvarsky, Tony DiGiloramo for the only submitted background, and anyone else whom 
I forgot to mention!

12. Contacting the Author

For any questions, comments, help needed, etc, contact me :

Ahmed El-Helw
ahmed3@worldnet.att.net
http://ahmed1.home.ml.org
IRC :  EFNet - Channel #ti-files, Nick : Ahmed or Ahmed|

Also, visit the premier TI Site - which I am a part of :
	http://ti-files.home.ml.org

ASM Journals of mine can be obtained at either site.




Ahmed El-Helw


